home *** CD-ROM | disk | FTP | other *** search
/ The Original Shareware 1.1 / The Original Shareware (WeMake CDs)(Volume 1.1)(CDs, Inc)(1993).iso / 16 / qmac11a.zip / QMAC.DOC < prev    next >
Text File  |  1988-05-27  |  7KB  |  195 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                              QMAC 1.1
  12.  
  13.    A utility for use with QEdit 2, the Quick Editor by SemWare
  14.  
  15.         Copyright 1988 by Sammy Mitchell and Karl Brendel
  16.  
  17.                        All rights reserved
  18.  
  19.  
  20.   QMAC is a translator of QEdit 2 macro files. It translates
  21. QEdit 2 macros from the binary file in which QEdit 2 saves macros
  22. to a text file which allows easy macro editing, and translates
  23. such text files to a QEdit 2 binary file. QMAC allows appending
  24. to or overwriting existing files, making it easy to add new
  25. macros to existing files. QMAC's text file format allows
  26. comments, permitting documentation of the macros within their
  27. "source file".
  28.  
  29.   Altho QMAC is a copyrighted work, it may be freely distributed,
  30. subject to the following conditions: QMAC must be distributed
  31. with full documentation, and with no modification of the program
  32. itself or the original documentation or any accompanying files,
  33. such as sample macro files, otherwise than herein provided.
  34. Users' groups and disk distributors may append brief documen-
  35. tation of their own. Other than nominal charges for disk dupli-
  36. cation services, no fee may be received for the distribution of
  37. the QMAC files without the written permission of Sammy Mitchell
  38. or Karl Brendel. Distributors who already have permission to
  39. distribute QEdit 2 are exempt from this requirement.
  40.  
  41.   No registration fee is required for the continuing use of QMAC.
  42.  
  43.   Changes in the documentation since the last release are marked
  44. with | in the right margin.
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.   To run QMAC, at the DOS prompt type:
  53.  
  54.             QMAC [?] [bfn] [tfn] [om] [am]
  55.  
  56. and press Enter. The items shown in [] are parameters which may
  57. be entered at the DOS prompt. Do not type the []. QMAC will
  58. prompt for any required parameters which are not supplied at the
  59. DOS prompt. If parameters are provided at the DOS prompt, they
  60. must be given in the order shown, except that the [?] should be
  61. entered only if requesting help. If the [?] appears as the first
  62. parameter, all other parameters at the DOS prompt are ignored.
  63. Parameters which are not required may be omitted, and will be
  64. ignored if given.
  65.  
  66.   The parameters are:
  67.  
  68.             ?   == request for a help summary
  69.             bfn == filespec of the compiled macro file
  70.             tfn == filespec of the text macro file
  71.             om  == output mode : T(ext) or B(inary)
  72.             am  == append mode : Y(es) or N(o)
  73.  
  74. [om] and [am] are required only if [bfn] and [tfn] both specify
  75. existing files. If only one of the files is existing, [om] is
  76. determined by the type of the existing file: if the existing file
  77. is Text, [om] is Binary, and vice versa. If [am] is Y(es) then
  78. output is appended to the existing file; if N(o), the existing
  79. file is overwritten.
  80.  
  81.   After processing any parameters from the DOS prompt, QMAC
  82. itself will prompt for any further parameters needed. When all
  83. such parameters have been provided, QMAC will process the macros
  84. as required.
  85.  
  86.   Answering any QMAC prompt by merely pressing Enter will halt
  87. QMAC.
  88.  
  89.   Answering the prompt for [bfn] with a ? will display the help
  90. summary just as if [?] had been provided at the DOS prompt.
  91.  
  92.   QMAC is crash-resistant, but does not make a lot of effort to
  93. deal with missing files, open disk drives, etc. Encountering an
  94. error it cannot deal with, QMAC will halt with a (hopefully
  95. informative) message.
  96.  
  97.   QMAC can deal with many errors in a macro text file by skipping
  98. to the next macro. It will display the line where the error was
  99. discovered.
  100.  
  101.   The contents of a macro text file are blank lines, comment
  102. lines, and macro lines. QMAC skips blank lines and comment lines.
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.   Comment lines have a * in the first column:
  112.  
  113. * This is a comment line.
  114.  * This is not a comment line and QMAC will reject it.
  115.  
  116. The leading space in the second example line prevents it from
  117. being a comment. Comment lines may be of any length. Note that
  118. comments are not placed in the binary file, and so will not show
  119. up in a text file which has been translated from a binary file.
  120. The primary purpose of comments is to allow documentation of
  121. macro source files.
  122.  
  123.   The first line of a macro must start with the key designator,
  124. followed by the command macro_begin, as shown in the QCONFIG.DAT
  125. file distributed with QEdit 2. An example:
  126.  
  127. ^i macro_begin cursor_up word_right cursor_down
  128.  
  129. The key designator does not have to be in the first column. The
  130. commands may be written in any mixture of upper and lower case,
  131. and do not require the _ character commonly used. This macro will
  132. translate identically to the previous one:
  133.  
  134.     ^I MaCrObEgIn CuRsOrUp WoRdRiGhT cUrSoRdOwN
  135.  
  136.   A macro line is limited to 255 characters, including all
  137. spaces. If QMAC reads a line 255 characters long, it will issue a
  138. warning that the macro may have been truncated. Macros may
  139. continue to an arbitrary number of lines. (Note that no check is
  140. made against QEdit 2's allocation of storage for macros because
  141. that allocation may change from release to release.)  A macro
  142. line which is to be continued must have & as the last character.
  143. Comment lines and/or blank lines may be inserted between the
  144. lines of a continuing macro:
  145.  
  146. @p macrobegin markblockend wordleft markblockbegin endline &     |
  147.  
  148. * This is a continuing macro. Documenting comments for this macro
  149. * are in the accompanying file QMACROS.PAS.
  150.  
  151. return copyblock endline return copyblock                  &      |
  152. unmarkblock "end; {" endline
  153.  
  154. * Note that lines do not have to be 255 characters long
  155. * to be continued. Length less than that is arbitrary.
  156.  
  157. "}" cursorup endline "}" wordleft "begin {" cursorup endline &    |
  158. ";" wordleft "procedure " endline cursorleft
  159. * That's all of that one, folks!
  160.  
  161. Revisions:
  162.  
  163.   1.1--Adds support for new commands in QEdit 2.06.               |
  164.        Corrects bug where Qmac would write 64K of junk to the     |
  165. binary file if a key designator stood alone on a line.            |
  166.  
  167.   The "&" character at the end of each line (except the last one) |
  168. of a continuing macro is NOT optional. (It was omitted by error   |
  169. in the examples in the original documentation.)                   |
  170.  
  171.   Notice that literal strings appear between " marks, so that "{"
  172. means to insert { at the cursor. Literal strings which must
  173. contain " marks (for whatever reason) should include two " to
  174. display one:
  175.  
  176.        "a ""-marked string"
  177.  
  178. will result in a binary macro containing:
  179.  
  180.        a "-marked string
  181.  
  182.   Requests for help, bug reports, etc., may be directed to Karl
  183. Brendel on CompuServe (73307,3101), GEnie (K.BRENDEL), or at the
  184. bbs shown below. To express your undying gratitude for QMAC,
  185. please register QEdit 2 if you have not already, and pass it (and
  186. QMAC) around for others.
  187.  
  188.   Contact points for QMAC:
  189.  
  190.                  Sleepy Hollow       213 859 9334
  191.                  Software Society    201 729 7410
  192.                  Tamiami PC Board    813 793 2392
  193.  
  194.  
  195.